

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Parameters &mdash; CodeCarbon 3.1.1 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="_static/documentation_options.js?v=796a81b5"></script>
      <script src="_static/doctools.js?v=9bcbadda"></script>
      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Examples" href="examples.html" />
    <link rel="prev" title="CodeCarbon API" href="api.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="index.html" class="icon icon-home">
            CodeCarbon
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Introduction</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="motivation.html">Motivation</a></li>
<li class="toctree-l1"><a class="reference internal" href="methodology.html">Methodology</a></li>
<li class="toctree-l1"><a class="reference internal" href="rapl.html">RAPL Metrics</a></li>
<li class="toctree-l1"><a class="reference internal" href="model_examples.html">Model Comparisons</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Getting Started</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installing CodeCarbon</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#configuration">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">CodeCarbon API</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Parameters</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#input-parameters">Input Parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="#output-parameters">Output parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="#specific-parameters-for-offline-mode">Specific parameters for offline mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="#track-emissions">&#64;track_emissions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="comet.html">Comet Integration</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced_installation.html">Advanced Installation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Logging</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="output.html">Output</a></li>
<li class="toctree-l1"><a class="reference internal" href="to_logger.html">Collecting emissions to a logger</a></li>
<li class="toctree-l1"><a class="reference internal" href="visualize.html">Visualize</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">CodeCarbon</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">Parameters</li>
      <li class="wy-breadcrumbs-aside">
            <a href="_sources/parameters.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="parameters">
<span id="id1"></span><h1>Parameters<a class="headerlink" href="#parameters" title="Link to this heading"></a></h1>
<p>A set of parameters are supported by API to help users provide additional details per project.</p>
<section id="input-parameters">
<h2>Input Parameters<a class="headerlink" href="#input-parameters" title="Link to this heading"></a></h2>
<table class="docutils align-center" id="id6">
<caption><span class="caption-text">Input Parameters</span><a class="headerlink" href="#id6" title="Link to this table"></a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>project_name</p></td>
<td><p>Name of the project, defaults to <code class="docutils literal notranslate"><span class="pre">codecarbon</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>experiment_id</p></td>
<td><p>Id of the experiment</p></td>
</tr>
<tr class="row-even"><td><p>measure_power_secs</p></td>
<td><p>Interval (in seconds) to measure hardware power usage, defaults to <code class="docutils literal notranslate"><span class="pre">15</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>tracking_mode</p></td>
<td><div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">machine</span></code> measure the power consumptions of the entire machine (default)</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">process</span></code> try and isolate the tracked processes in isolation</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>gpu_ids</p></td>
<td><div class="line-block">
<div class="line">Comma-separated list of GPU ids to track, defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code></div>
<div class="line">These can either be integer indexes of GPUs on the system, or prefixes</div>
<div class="line">to match against GPU identifiers as described <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#cuda-environment-variables">here</a></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>log_level</p></td>
<td><div class="line-block">
<div class="line">Global codecarbon log level (by order of verbosity): “debug”, “info” (default),</div>
<div class="line">“warning”, “error”, or “critical”</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>electricitymaps_api_token</p></td>
<td><div class="line-block">
<div class="line">API token for electricitymaps.com (formerly co2signal.com)</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>pue</p></td>
<td><div class="line-block">
<div class="line">PUE (Power Usage Effectiveness) of the data center</div>
<div class="line">where the experiment is being run.</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>wue</p></td>
<td><div class="line-block">
<div class="line">WUE (Water Usage Effectiveness) of the data center</div>
<div class="line">where the experiment is being run.</div>
<div class="line">Units of <em>L/kWh</em> - how many litres of water are consumed per kilowatt-hour</div>
<div class="line">of electricity consumed.</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>force_cpu_power</p></td>
<td><div class="line-block">
<div class="line">Force the CPU max power consumption in watts,</div>
<div class="line">use this if you know the TDP of your machine.</div>
<div class="line"><em>(POWER_CONSTANT x CONSUMPTION_PERCENTAGE)</em></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>force_ram_power</p></td>
<td><div class="line-block">
<div class="line">Force the RAM power consumption in watts,</div>
<div class="line">use this if you know the power consumption of your RAM.</div>
<div class="line">Estimate it with <code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">lshw</span> <span class="pre">-C</span> <span class="pre">memory</span> <span class="pre">-short</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">DIMM</span></code></div>
<div class="line">to get the number of RAM slots used, then do</div>
<div class="line"><em>RAM power in W = Number of RAM Slots * 5 Watts</em></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>rapl_include_dram</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if DRAM (memory) power should be included</div>
<div class="line">in RAPL measurements on Linux systems, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</div>
<div class="line">When <code class="docutils literal notranslate"><span class="pre">True</span></code>, measures complete hardware power (CPU package + DRAM).</div>
<div class="line">Set to <code class="docutils literal notranslate"><span class="pre">False</span></code> to measure only CPU package power.</div>
<div class="line">Note: Only affects systems where RAPL exposes separate DRAM domains.</div>
<div class="line">In a future version DRAM power will probably be included in RAM.</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>rapl_prefer_psys</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if psys (platform/system) RAPL domain should be</div>
<div class="line">preferred over package domains on Linux systems, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</div>
<div class="line">When <code class="docutils literal notranslate"><span class="pre">True</span></code>, uses psys domain for total platform power (CPU + chipset + PCIe).</div>
<div class="line">When <code class="docutils literal notranslate"><span class="pre">False</span></code> (default), uses package domains which are more reliable and</div>
<div class="line">consistent with CPU TDP specifications.</div>
<div class="line">Note: psys can report higher values than CPU TDP and may be unreliable on older systems.</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>allow_multiple_runs</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if multiple instance of CodeCarbon</div>
<div class="line">on the same machine is allowed,</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code> since v3. Used to be <code class="docutils literal notranslate"><span class="pre">False</span></code> in v2.</div>
</div>
</td>
</tr>
</tbody>
</table>
<p>PUE is a multiplication factor provided by the user, so it is up to the user to get it from their cloud provider.
Old data-centers have a PUE up to 2.2, where new greener ones could be as low as 1.1.</p>
<p>If you, or your provider, use <code class="docutils literal notranslate"><span class="pre">CUDA_VISIBLE_DEVICES</span></code> to set the GPUs you want to use, CodeCarbon will automaticly populate this value into <code class="docutils literal notranslate"><span class="pre">gpu_ids</span></code>.
If you set <code class="docutils literal notranslate"><span class="pre">gpu_ids</span></code> manually, it will override the <code class="docutils literal notranslate"><span class="pre">CUDA_VISIBLE_DEVICES</span></code> for CodeCarbon measures.</p>
</section>
<section id="output-parameters">
<h2>Output parameters<a class="headerlink" href="#output-parameters" title="Link to this heading"></a></h2>
<table class="docutils align-center" id="id7">
<caption><span class="caption-text">Output Parameters</span><a class="headerlink" href="#id7" title="Link to this table"></a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><strong>save_to_file</strong></p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if the emission artifacts should be logged</div>
<div class="line">to a CSV file, defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>output_dir</p></td>
<td><div class="line-block">
<div class="line">Directory path to which the experiment details are logged</div>
<div class="line">defaults to current directory</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>output_file</p></td>
<td><div class="line-block">
<div class="line">Name of output CSV file</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">emissions.csv</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>on_csv_write</p></td>
<td><div class="line-block">
<div class="line">When calling <code class="docutils literal notranslate"><span class="pre">tracker.flush()</span></code> manually choose if</div>
<div class="line">- <code class="docutils literal notranslate"><span class="pre">update</span></code> the existing <code class="docutils literal notranslate"><span class="pre">run_id</span></code> row (erasing former data)</div>
<div class="line">- <code class="docutils literal notranslate"><span class="pre">append</span></code> add a new row to CSV file (defaults)</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p><strong>save_to_api</strong></p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if emissions artifacts should be logged</div>
<div class="line">to the CodeCarbon API, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>api_endpoint:</p></td>
<td><div class="line-block">
<div class="line">Optional URL of CodeCarbon API endpoint for sending emissions data</div>
<div class="line">defaults to “<a class="reference external" href="https://api.codecarbon.io">https://api.codecarbon.io</a>”</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>api_key</p></td>
<td><p>API key for the CodeCarbon API (mandatory to use this API!)</p></td>
</tr>
<tr class="row-odd"><td><p>api_call_interval</p></td>
<td><div class="line-block">
<div class="line">Number of measurements between API calls (defaults to 8):</div>
<div class="line">-1 : call API on flush() and at the end</div>
<div class="line">1 : at every measure</div>
<div class="line">2 : at every 2 measure, and so on</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p><strong>save_to_logger</strong></p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if the emission artifacts should be written</div>
<div class="line">to a dedicated logger, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>logging_logger</p></td>
<td><p>LoggerOutput object encapsulating a logging.Logger or a Google Cloud logger</p></td>
</tr>
<tr class="row-even"><td><p>logger_preamble</p></td>
<td><p>String to systematically include in the logger’s messages (defaults to “”)</p></td>
</tr>
<tr class="row-odd"><td><p>save_to_prometheus</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if the emission artifacts should be written</div>
<div class="line">to a Prometheus server, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>prometheus_url</p></td>
<td><div class="line-block">
<div class="line">URL of the Prometheus server</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>save_to_logfire</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if the emission artifacts should be written</div>
<div class="line">to a LogFire server, defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>output_handlers</p></td>
<td><div class="line-block">
<div class="line">List of output handlers to use for saving the emissions data</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">[]</span></code></div>
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section id="specific-parameters-for-offline-mode">
<h2>Specific parameters for offline mode<a class="headerlink" href="#specific-parameters-for-offline-mode" title="Link to this heading"></a></h2>
<table class="docutils align-center" id="id8">
<caption><span class="caption-text">Input Parameters to OfflineEmissionsTracker</span><a class="headerlink" href="#id8" title="Link to this table"></a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>country_iso_code</p></td>
<td><div class="line-block">
<div class="line">3-letter ISO Code of the country</div>
<div class="line">where the experiment is being run.</div>
<div class="line">Available countries are listed in <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/private_infra/global_energy_mix.json">global_energy_mix.json</a></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>region</p></td>
<td><div class="line-block">
<div class="line">Optional name of the Province/State/City, where the infrastructure is hosted</div>
<div class="line">Currently, supported only for US States and Canada</div>
<div class="line">for example - California or New York, from the <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/private_infra/2016/usa_emissions.json">list</a></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>cloud_provider</p></td>
<td><div class="line-block">
<div class="line">The cloud provider specified for estimating emissions intensity,</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>. See <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/cloud/impact.csv">impact.csv</a> for a list of cloud providers</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>cloud_region</p></td>
<td><div class="line-block">
<div class="line">The region of the cloud data center, defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code></div>
<div class="line">See <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/cloud/impact.csv">impact.csv</a> for a list of cloud regions.</div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>country_2letter_iso_code</p></td>
<td><div class="line-block">
<div class="line">For use with the Electricity Maps emissions API.</div>
<div class="line">See <a class="reference external" href="http://api.electricitymap.org/v3/zones">Electricity Maps zones</a> for a list of codes and their locations.</div>
</div>
</td>
</tr>
</tbody>
</table>
</section>
<section id="track-emissions">
<h2>&#64;track_emissions<a class="headerlink" href="#track-emissions" title="Link to this heading"></a></h2>
<p>Decorator <code class="docutils literal notranslate"><span class="pre">track_emissions</span></code> in addition to standard arguments, requires the following parameters:</p>
<table class="docutils align-center" id="id9">
<caption><span class="caption-text">Input Parameters to &#64;track_emissions</span><a class="headerlink" href="#id9" title="Link to this table"></a></caption>
<colgroup>
<col style="width: 20.0%" />
<col style="width: 80.0%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>fn</p></td>
<td><p>function to be decorated</p></td>
</tr>
<tr class="row-odd"><td><p>offline</p></td>
<td><div class="line-block">
<div class="line">Boolean variable indicating if the tracker should be run in offline mode</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>country_iso_code</p></td>
<td><div class="line-block">
<div class="line">3 letter ISO Code of the country where the experiment is being run.</div>
<div class="line">Available countries are listed in <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/private_infra/2016/global_energy_mix.json">global_energy_mix.json</a></div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>region</p></td>
<td><div class="line-block">
<div class="line">Optional Name of the Province/State/City, where the infrastructure is hosted</div>
<div class="line">Currently, supported only for US States</div>
<div class="line">for example - California or New York, from the <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/private_infra/2016/usa_emissions.json">list</a></div>
</div>
</td>
</tr>
<tr class="row-even"><td><p>cloud_provider</p></td>
<td><div class="line-block">
<div class="line">The cloud provider specified for estimating emissions intensity,</div>
<div class="line">defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>. See <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/cloud/impact.csv">impact.csv</a> for a list of cloud providers</div>
</div>
</td>
</tr>
<tr class="row-odd"><td><p>cloud_region</p></td>
<td><div class="line-block">
<div class="line">The region of the cloud data center, defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code></div>
<div class="line">See <a class="reference external" href="https://github.com/mlco2/codecarbon/blob/master/codecarbon/data/cloud/impact.csv">impact.csv</a> for a list of cloud regions.</div>
</div>
</td>
</tr>
</tbody>
</table>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="api.html" class="btn btn-neutral float-left" title="CodeCarbon API" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="examples.html" class="btn btn-neutral float-right" title="Examples" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2020, BCG GAMMA, Comet.ml, Haverford College, MILA.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>